中文 | English

人人都在讨论 Ralph。它到底是什么？

Ralph 是一种自主 AI 编码循环，能在你睡觉时持续交付功能。

它由 @GeoffreyHuntley 创建，并在他的原始帖子中公布；它会反复运行 @AmpCode（或者你选择的其他 agent），直到所有任务都完成。

每一次迭代都是一个全新的上下文窗口（让 Threads 保持很小）。记忆则通过 git 历史和文本文件持久化。

我第一次跑它是在昨晚，结果真的交付了一个功能。我很喜欢。

1 月 6 日

我甚至还没上床。它就已经做完了。很震撼。

它如何工作

（这里有一个完整的 GitHub 仓库，你可以下载后直接试。）

一个 bash 循环会：

1. 把 prompt 通过管道输送给你的 AI agent
2. Agent 从 prd.json 中挑选下一个 story
3. Agent 实现它
4. Agent 运行 typecheck 和 tests
5. 如果通过就提交 commit
6. Agent 把 story 标记为完成
7. Agent 记录新的经验
8. 循环继续，直到全部完成

记忆只通过以下方式持久化：

• Git commits
• progress.txt（经验记录）
• prd.json（任务状态）

文件结构

scripts/ralph/
├── ralph.sh
├── prompt.md
├── prd.json
└── progress.txt

ralph.sh

这个循环本体如下：

#!/bin/bash
set -e

MAX_ITERATIONS=${1:-10}
SCRIPT_DIR="$(cd "$(dirname \
  "${BASH_SOURCE[0]}")" && pwd)"

echo "🚀 Starting Ralph"

for i in $(seq 1 $MAX_ITERATIONS); do
  echo "═══ Iteration $i ═══"
  
  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" \
    | amp --dangerously-allow-all 2>&1 \
    | tee /dev/stderr) || true
  
  if echo "$OUTPUT" | \
    grep -q "<promise>COMPLETE</promise>"
  then
    echo "✅ Done!"
    exit 0
  fi
  
  sleep 2
done

echo "⚠️ Max iterations reached"
exit 1

把它设为可执行：

chmod +x scripts/ralph/ralph.sh

其他 agent：

• Claude Code: claude --dangerously-skip-permissions

prompt.md

每一轮迭代的指令如下：

# Ralph Agent Instructions

## Your Task

1. Read `scripts/ralph/prd.json`
2. Read `scripts/ralph/progress.txt`
   (check Codebase Patterns first)
3. Check you're on the correct branch
4. Pick highest priority story 
   where `passes: false`
5. Implement that ONE story
6. Run typecheck and tests
7. Update AGENTS.md files with learnings
8. Commit: `feat: [ID] - [Title]`
9. Update prd.json: `passes: true`
10. Append learnings to progress.txt

## Progress Format

APPEND to progress.txt:

## [Date] - [Story ID]
- What was implemented
- Files changed
- **Learnings:**
  - Patterns discovered
  - Gotchas encountered
---

## Codebase Patterns

Add reusable patterns to the TOP 
of progress.txt:

## Codebase Patterns
- Migrations: Use IF NOT EXISTS
- React: useRef<Timeout | null>(null)

## Stop Condition

If ALL stories pass, reply:
<promise>COMPLETE</promise>

Otherwise end normally.

prd.json

这是你的任务清单：

{
  "branchName": "ralph/feature",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login form",
      "acceptanceCriteria": [
        "Email/password fields",
        "Validates email format",
        "typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

关键字段：

• branchName：要使用的分支
• priority：值越小越先做
• passes：完成后设为 true

progress.txt

从这些上下文开始：

# Ralph Progress Log
Started: 2024-01-15

## Codebase Patterns
- Migrations: IF NOT EXISTS
- Types: Export from actions.ts

## Key Files
- db/schema.ts
- app/auth/actions.ts
---

Ralph 会在每个 story 后继续追加。

模式会在多轮迭代中不断累积。

运行 Ralph

./scripts/ralph/ralph.sh 25

最多运行 25 轮迭代。

Ralph 会：

• 创建 feature branch
• 逐个完成 stories
• 每完成一个就提交一次
• 当全部通过时停止

成功的关键因素

1. 小 stories

必须能装进一个上下文窗口。

❌ 太大：
> "Build entire auth system"
✅ 合适：
> "Add login form"
> "Add email validation"
> "Add auth server action"

2. 反馈回路

Ralph 需要快速反馈：

• npm run typecheck
• npm test

没有这些，坏代码会不断累积。

3. 明确标准

❌ 模糊：
> "Users can log in"
✅ 明确：
> - Email/password fields
> - Validates email format
> - Shows error on failure
> - typecheck passes
> - Verify at localhost:$PORT/login (PORT defaults to 3000)

4. 经验会累积

到第 10 个 story 时，Ralph 已经知道前 1 到 9 个 story 里总结出来的模式。

经验有两个存放位置：

1. progress.txt：Ralph 各轮迭代的会话记忆
2. AGENTS.md：给人类和未来 agent 的永久文档

在提交之前，如果 Ralph 发现了可复用的模式（坑点、约定、依赖），它会更新被修改文件所在目录中的 AGENTS.md。

5. 更新 AGENTS.md

当 Ralph 学到值得长期保留的东西时，它会更新 AGENTS.md：

✅ 好的补充：
- "When modifying X, also update Y"
- "This module uses pattern Z"
- "Tests require dev server running"
❌ 不要添加：
- Story-specific details
- Temporary notes
- Info already in progress.txt

6. 浏览器测试

对于 UI 改动，使用 @sawyerhood 的 dev-browser skill。用 Load the dev-browser skill 加载它，然后：

# Start the browser server
~/.config/amp/skills/dev-browser/server.sh &
# Wait for "Ready" message

# Write scripts using heredocs
cd ~/.config/amp/skills/dev-browser && npx tsx <<'EOF'
import { connect, waitForPageLoad } from "@/client.js";

const client = await connect();
const page = await client.page("test");
await page.setViewportSize({ width: 1280, height: 900 });
const port = process.env.PORT || "3000";
await page.goto(`http://localhost:${port}/your-page`);
await waitForPageLoad(page);
await page.screenshot({ path: "tmp/screenshot.png" });
await client.disconnect();
EOF

没有截图验证，就不算完成。

常见坑点

幂等迁移：

ADD COLUMN IF NOT EXISTS email TEXT;

交互式提示：

echo -e "\n\n\n" | npm run db:generate

Schema 变更：

编辑 schema 之后，要检查：

• Server actions
• UI components
• API routes

可以顺手修相关文件：

如果 typecheck 因此要求你改别的文件，那就改。这不算 scope creep。

监控

# Story status
cat scripts/ralph/prd.json | \
jq '.userStories[] | {id, passes}'
# Learnings
cat scripts/ralph/progress.txt
# Commits
git log --oneline -10

真实结果

我们曾用它搭了一个评估系统：

• 13 个 user stories
• 大约 15 轮迭代
• 每轮 2 到 5 分钟
• 总计大约 1 小时

经验会不断叠加。到第 10 个 story 时，Ralph 已经知道了我们的模式。

什么时候不该用

• 探索性工作
• 没有明确标准的大型重构
• 安全关键代码
• 任何需要人工审查的内容

如果你想看一个很好的 Ralph 使用视频讲解，可以去看 @mattpocockuk 的视频……

1 月 5 日

我对 Ralph Wiggum 的拆解火了。这是一种 keep-it-simple-stupid 的 AI 编码方法，让你睡觉时也能持续交付。所以下面我会给出完整解释、示例代码和演示。